IEP Marking Definition Version 2.0 for STIX™ Version 2.1

Editors:

Additional artifacts:

Information Exchange Policy 2.0 Framework Definition – FIRST specification. This prose specification is one component of a Work Product that also includes:
STIX™ Version 2.1 – OASIS specification

Related work:

This specification replaces or supersedes:

Abstract:

The FIRST Information Exchange Policy (IEP) 2.0 Framework Definition specifies how Computer Security Incident Response Teams (CSIRTs), security communities, organizations, and vendors may support their information sharing and information exchange initiatives.

The framework is intended to support both CSIRT’s existing policies to define information exchange and new policies to define matured and evolved CSIRT information exchange. This document defines the approach to express IEP 2.0 using Structured Threat Information Expression (STIX^TM) language via the use of a marking definition object.

1. Data Markings in STIX

Data markings represent restrictions, permissions, and other guidance for how data can be used and shared. For example, data may be shared with the restriction that it must not be re-shared, or that it must be encrypted at rest. In STIX, data markings are specified using the marking-definition object. For general information on data markings in STIX, see section 7.2 of STIX™ Version 2.1 - OASIS specification.

2. The Information Exchange Policy (IEP) Marking Object Type

The Information Exchange Policy (IEP) marking definition type, version 2.0, defines the STIX object types required to share the IEP 2.0 standard. IEP is intended to support both CSIRT’s existing policies to define information exchange and new policies to define matured and evolved CSIRT information exchange. Information sharing happens from a provider, towards one or more recipients.

Because IEP 2.0 data markings are not part of the STIX 2.1 specification, they must be specified using the Extension Definition object as described in section 7.3 of the specification.

The tables below describe the properties of a STIX 2.1 IEP 2.0 marking definition type. These properties are based on the marking-definition object type described in section 7.2 of the STIX 2.1 specification. Notice that the deprecated properties of the marking definition object type are not used.

Note that when using this extension, external_references is required.

Required Common Properties
type, spec_version, id, created, extensions, external_references

Required Common Properties

type, spec_version, id, created, extensions, external_references

Optional Common Properties

Not Applicable Common Properties
confidence, defanged, created_by_ref, granular_markings, labels, lang, modified, object_marking_refs, revoked

Not Applicable Common Properties

confidence, defanged, created_by_ref, granular_markings, labels, lang, modified, object_marking_refs, revoked

Property Name	Type	Description
type (required)	string	The type property identifies the type of object. The value of this property MUST be marking-definition.
name (required)	string	This statement can be used to provide a name for an IEP Marking Definition implementation
extensions (required)	dictionary	Specifies the IEP 2.0 marking “color” as an extension dictionary. There MUST be only one dictionary key and it MUST be extension-definition—762e2e97-ee51-43e5-a9ea-165fbb862c4a, which is the id of the extension-definition object associated with IEP-2.0. The corresponding dictionary values MUST be the iep-2-0-content data type described below.

Property Name

Type

Description

type (required)

string

The type property identifies the type of object. The value of this property MUST be marking-definition.

name (required)

string

This statement can be used to provide a name for an IEP Marking Definition implementation

extensions (required)

dictionary

Specifies the IEP 2.0 marking “color” as an extension dictionary.

There MUST be only one dictionary key and it MUST be extension-definition—762e2e97-ee51-43e5-a9ea-165fbb862c4a, which is the id of the extension-definition object associated with IEP-2.0.

The corresponding dictionary values MUST be the iep-2-0-content data type described below.

Type Name: iep-2-0-content

Property Name	Type	Description
extension_type (required)	string	The extension_type property indicates the type of extension is being used. The value of this property MUST be property-extension
encrypt_in_transit (required)	string	States whether the received information has to be encrypted when it is retransmitted by the recipient. The value of this property MUST be one of the following: must may
permitted_actions (required)	enum	States the permitted actions that recipients can take upon information received. The value of this property MUST come from the iep-permitted-actions-enum enumeration.
affected_party_notifications (required)	string	Recipients are permitted to notify affected third parties of a compromise or threat. The value of this property MUST be one of the following: may must-not
tlp (required)	string	Recipients are permitted to redistribute the information received within the redistribution scope as defined by the enumerations. The value of this property MUST be one of the following: red amber green white
provider_attribution (required)	string	Recipients could be required to attribute or anonymize the provider when redistributing the information received. The value of this property MUST be one of the following: may must must-not
unmodified_resale (required)	string	States whether the recipient MAY or MUST NOT resell the information received unmodified or in a semantically equivalent format. The value of this property MUST be one of the following: may must-not
iep_id (required)	string	Provides a unique ID to identify a specific IEP implementation. The policy ID must be either UUIDv4 or UUIDv5 as specified in RFC4122
iep_version (required)	float	Defines which version of the IEP Framework this policy implements. The value of this property MUST be 2.0, as this extension does not cover earlier versions.
description (required)	string	This statement can be used to provide some background information about the IEP implementation.
start_date (required)	timestamp	States the UTC date that an IEP is effective from.
end_date (optional)	timestamp	States the UTC date that an IEP is effective until.

Property Name

Type

Description

extension_type (required)

string

The extension_type property indicates the type of extension is being used. The value of this property MUST be property-extension

encrypt_in_transit (required)

string

States whether the received information has to be encrypted when it is retransmitted by the recipient.

The value of this property MUST be one of the following:

must

may

permitted_actions (required)

enum

States the permitted actions that recipients can take upon information received.

The value of this property MUST come from the iep-permitted-actions-enum enumeration.

affected_party_notifications (required)

string

Recipients are permitted to notify affected third parties of a compromise or threat.

The value of this property MUST be one of the following:

may

must-not

tlp (required)

string

Recipients are permitted to redistribute the information received within the redistribution scope as defined by the enumerations.

The value of this property MUST be one of the following:

red

amber

green

white

provider_attribution (required)

string

Recipients could be required to attribute or anonymize the provider when redistributing the information received.

The value of this property MUST be one of the following:

may

must

must-not

unmodified_resale (required)

string

States whether the recipient MAY or MUST NOT resell the information received unmodified or in a semantically equivalent format.

The value of this property MUST be one of the following:

may

must-not

iep_id (required)

string

Provides a unique ID to identify a specific IEP implementation. The policy ID must be either UUIDv4 or UUIDv5 as specified in RFC4122

iep_version (required)

float

Defines which version of the IEP Framework this policy implements. The value of this property MUST be 2.0, as this extension does not cover earlier versions.

description (required)

string

This statement can be used to provide some background information about the IEP implementation.

start_date (required)

timestamp

States the UTC date that an IEP is effective from.

end_date (optional)

timestamp

States the UTC date that an IEP is effective until.

Enumerations

Type Name: iep-permitted-actions-enum

Vocabulary Value	Description
none	Recipients SHOULD NOT act upon the information received. The information SHOULD only be used for internal informational purposes, and internally visible actions, externally visible indirect actions and externally visible direct actions SHOULD NOT be performed.
contact-for-instruction	Recipients MUST contact the Providers before acting upon the information received. An example is where information redacted by the Provider could be derived by the Recipient and identify the affected parties.
internally-visible-actions	Recipients MAY conduct actions on the information received that are only visible on the Recipient’s internal networks and systems, and MUST NOT conduct actions that are visible outside of the Recipients networks and systems, or visible to third parties.
externally-visible-indirect-actions	Recipients MAY conduct internally visible actions, and MAY also conduct indirect, or passive, actions on the information received. Recipients MUST NOT conduct direct, or active, actions that will be visible by Threat Actors mentioned within the shared information.
externally-visible-direct-actions	Recipients MAY conduct any actions on the information received.

Vocabulary Value

Description

none

Recipients SHOULD NOT act upon the information received. The information SHOULD only be used for internal informational purposes, and internally visible actions, externally visible indirect actions and externally visible direct actions SHOULD NOT be performed.

contact-for-instruction

Recipients MUST contact the Providers before acting upon the information received. An example is where information redacted by the Provider could be derived by the Recipient and identify the affected parties.

internally-visible-actions

Recipients MAY conduct actions on the information received that are only visible on the Recipient’s internal networks and systems, and MUST NOT conduct actions that are visible outside of the Recipients networks and systems, or visible to third parties.

externally-visible-indirect-actions

Recipients MAY conduct internally visible actions, and MAY also conduct indirect, or passive, actions on the information received. Recipients MUST NOT conduct direct, or active, actions that will be visible by Threat Actors mentioned within the shared information.

externally-visible-direct-actions

Recipients MAY conduct any actions on the information received.

3. Extension Definition Object for IEP 2.0

{
    "id": "extension-definition--762e2e97-ee51-43e5-a9ea-165fbb862c4a",
    "type": "extension-definition",
    "spec_version": "2.1",
    "name": "IEP 2.0",
    "description": "This defines IEP 2.0 as a STIX extension",
    "created": "2022-12-19T00:00:00.000Z",
    "modified": "2022-12-19T00:00:00.000Z",
    "created_by_ref": "identity--b3bca3c2-1f3d-4b54-b44f-dac42c3a8f01",
    "schema": "https://github.com/oasis-open/cti-stix-common-objects/tree/master/extension-definition-specifications/iep-marking-definition-762",
    "version": "1.0.0",
    "extension_types": [
        "property-extension"
    ]
}

4. IEP 2.0 Data Marking Example

Basic example of the IEP Data Marking

{
    "type": "marking-definition",
    "spec_version": "2.1",
    "id": "marking-definition--da05d443-ad8d-46fc-abf5-31d3d00290f1",
    "created": "2024-01-10T14:52:41.853121Z",
    "name": "IEP data marking",
    "extensions": {
        "extension-definition--762e2e97-ee51-43e5-a9ea-165fbb862c4a": {
            "extension_type": "property-extension",
            "encrypt_in_transit": "may",
            "permitted_actions": "externally-visible-direct-actions",
            "affected_party_notifications": "may",
            "tlp": "amber",
            "provider_attribution": "must-not",
            "unmodified_resale": "must-not",
            "iep_id": "0224bfdf-ea3a-49c3-96f6-66d908bb1845",
            "iep_version": 2.0,
            "description": "This is a TLP-AMBER Information Exchange Policy",
            "start_date": "2022-10-01T00:00:00Z"
        }
    }
}

Basic example with optional end date field

{
    "type": "marking-definition",
    "spec_version": "2.1",
    "id": "marking-definition--da05d443-ad8d-46fc-abf5-31d3d00290f1",
    "created": "2024-01-10T14:52:41.853121Z",
    "name": "IEP data marking",
    "extensions": {
        "extension-definition--762e2e97-ee51-43e5-a9ea-165fbb862c4a": {
            "extension_type": "property-extension",
            "encrypt_in_transit": "may",
            "permitted_actions": "externally-visible-direct-actions",
            "affected_party_notifications": "may",
            "tlp": "amber",
            "provider_attribution": "must-not",
            "unmodified_resale": "must-not",
            "iep_id": "0224bfdf-ea3a-49c3-96f6-66d908bb1845",
            "iep_version": 2.0,
            "description": "This is a TLP-AMBER Information Exchange Policy",
            "start_date": "2022-10-01T00:00:00Z"
        }
    }
}

Example of the Bundle with an IEP Data Marking

{
    "type": "bundle",
    "id": "bundle--1b068194-6f34-4a7f-b73d-407d8375b81d",
    "objects": [
        { 
            "type": "marking-definition", 
            "spec_version": "2.1", 
            "id": "marking-definition--d68dc6bf-c181-424b-85e1-5a92868f01b6", 
            "created": "2022-10-01T00:00:00.000Z", 
            "name": "IEP data marking",
            "external_references": [
                {
                    "source_name": "IEP",
                    "description": "Information Exchange Policy",
                    "url": "https://www.first.org/iep"
                },
                {
                    "source_name": "TLP",
                    "description": "Traffic Light Protocol",
                    "url": "https://www.first.org/tlp"
                }
            ],
            "extensions": {
                "extension-definition--762e2e97-ee51-43e5-a9ea-165fbb862c4a": {
                    "extension_type": "property-extension",
                    "encrypt_in_transit": "may",
                    "permitted_actions": "externally-visible-direct-actions",
                    "affected_party_notifications": "may",
                    "tlp": "amber",
                    "provider_attribution": "must-not",
                    "unmodified_resale": "must-not",
                    "iep_id": "0224bfdf-ea3a-49c3-96f6-66d908bb1845",
                    "iep_version": 2.0,
                    "description": "This is a TLP-AMBER Information Exchange Policy",
                    "start_date": "2022-10-01T00:00:00.000Z"
                }
            }
        }
    ]
}

IEP Marking Definition Version 2.0 for STIX™ Version 2.1

Abstract:

1.​ Data Markings in STIX

2. The Information Exchange Policy (IEP) Marking Object Type

Enumerations

3. Extension Definition Object for IEP 2.0

4. IEP 2.0 Data Marking Example

1. Data Markings in STIX